Skip to content

docs: add llms.txt support via starlight-llms-txt plugin - #3955

Open
brad-dow wants to merge 2 commits into
mainfrom
bd/llms-txt
Open

docs: add llms.txt support via starlight-llms-txt plugin#3955
brad-dow wants to merge 2 commits into
mainfrom
bd/llms-txt

Conversation

@brad-dow

@brad-dow brad-dow commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

Description of changes
Installed starlight-llms-txt and configured for Rafiki. The plugin generates three routes at build time:

  • /llms.txt - curated index with project description and section links
  • /llms-full.txt - complete documentation in a single flat file
  • /llms-small.txt - condensed version with asides and whitespace collapsed

Special configuration for Rafiki:

  • details block explains Rafiki's audience (ASEs running the software on their own infrastructure, not developers consuming a hosted API), clarifies terminology (wallet addresses, peering, GNAP), notes the split between the GraphQL Admin APIs and the Open Payments REST API, and calls out the TigerBeetle/PostgreSQL accounting split
  • customSets groups content into five named subsets (Overview and concepts, Integration, Administration, APIs, Resources) mirroring the sidebar structure - this helps agents pull targeted content instead of the whole file
  • optionalLinks points to the GitHub repo and the Open Payments documentation that Rafiki implements
  • exclude: ['v1-beta/**'] keeps the older versioned docs (via starlight-versions) out of the generated files so we don't duplicate 99.9% of the content

Checklist

  • PR title is prefixed with docs:
  • PR title or description includes a fixes #
  • You've run pnpm format and pnpm lint
  • You've reviewed Vale errors and made changes where appropriate

@netlify

netlify Bot commented Jul 24, 2026 •
edited
Loading

Copy link
Copy Markdown

✅ Deploy Preview for brilliant-pasca-3e80ec ready!

Name Link
🔨 Latest commit 3ac1084
🔍 Latest deploy log https://app.netlify.com/projects/brilliant-pasca-3e80ec/deploys/6a63ab7ec375ae0008eb8857
😎 Deploy Preview https://deploy-preview-3955--brilliant-pasca-3e80ec.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@github-actions github-actions Bot added the pkg: documentation Changes in the documentation package. label Jul 24, 2026
@github-actions

github-actions Bot commented Jul 24, 2026 •
edited
Loading

Copy link
Copy Markdown

🚀 Performance Test Results

Test Configuration:

  • VUs: 4
  • Duration: 1m0s

Test Metrics:

  • Requests/s: 48.41
  • Iterations/s: 16.13
  • Failed Requests: 0.00% (0 of 2908)
📜 Logs 

> performance@1.0.0 run-tests:testenv /home/runner/work/rafiki/rafiki/test/performance
> ./scripts/run-tests.sh -e test -k -q --vus 4 --duration 1m

Cloud Nine GraphQL API is up: http://localhost:3101/graphql
Cloud Nine Wallet Address is up: http://localhost:3100/
Happy Life Bank Address is up: http://localhost:4100/
cloud-nine-wallet-test-backend already set
cloud-nine-wallet-test-auth already set
happy-life-bank-test-backend already set
happy-life-bank-test-auth already set
     data_received..................: 1.0 MB 18 kB/s
     data_sent......................: 2.2 MB 37 kB/s
     http_req_blocked...............: avg=5.92µs   min=1.51µs   med=3.37µs   max=2.79ms   p(90)=4.19µs   p(95)=4.63µs  
     http_req_connecting............: avg=965ns    min=0s       med=0s       max=1.15ms   p(90)=0s       p(95)=0s      
     http_req_duration..............: avg=82.24ms  min=6.51ms   med=58.01ms  max=806.32ms p(90)=144.24ms p(95)=199.51ms
       { expected_response:true }...: avg=82.24ms  min=6.51ms   med=58.01ms  max=806.32ms p(90)=144.24ms p(95)=199.51ms
     http_req_failed................: 0.00%  ✓ 0         ✗ 2908
     http_req_receiving.............: avg=50.82µs  min=15.61µs  med=42.58µs  max=1.87ms   p(90)=62.7µs   p(95)=76.13µs 
     http_req_sending...............: avg=23.72µs  min=6.39µs   med=15.6µs   max=3.49ms   p(90)=25.09µs  p(95)=33.09µs 
     http_req_tls_handshaking.......: avg=0s       min=0s       med=0s       max=0s       p(90)=0s       p(95)=0s      
     http_req_waiting...............: avg=82.16ms  min=6.14ms   med=57.95ms  max=806.25ms p(90)=144.17ms p(95)=199.45ms
     http_reqs......................: 2908   48.411637/s
     iteration_duration.............: avg=247.86ms min=141.81ms med=204.01ms max=925.91ms p(90)=378.66ms p(95)=498.97ms
     iterations.....................: 969    16.131663/s
     vus............................: 4      min=4       max=4 
     vus_max........................: 4      min=4       max=4

melissahenderson
melissahenderson previously approved these changes Jul 24, 2026
View reviewed changes
Comment thread packages/documentation/astro.config.mjs Outdated
starlightLlmsTxt({
details: `Rafiki documentation is for Account Servicing Entities (ASEs) — regulated institutions such as banks, digital wallet providers, and mobile money operators — who want to run Rafiki to add Interledger and Open Payments functionality to their users' accounts. It is not documentation for an end-user product or a payment app.

Rafiki exposes several separate HTTP services rather than a single API surface: a GraphQL Admin API for managing the backend (peers, assets, wallet addresses, liquidity), a separate GraphQL Admin API for the auth service, an ILP connector, an Open Payments REST API that implements the Open Payments protocol, and an auto-peering server. Questions about configuring or operating a Rafiki instance are answered by the Admin APIs; questions about initiating or receiving payments are answered by the Open Payments API, which is specified independently at openpayments.dev.

@melissahenderson melissahenderson Jul 24, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Open Payments contains multiple APIs, but if that's too tricky to relay we can leave it singular for now.

@brad-dow brad-dow Jul 24, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch and I'll clarify this a bit better in another commit

Comment thread packages/documentation/astro.config.mjs

Rafiki supports two interchangeable accounting backends: TigerBeetle (the default, purpose-built for financial accounting) and PostgreSQL (an alternative for deployments that prefer a single database). Integration guidance does not change based on which is used.

This site publishes documentation for multiple Rafiki versions. Prefer the current/default version unless the user explicitly asks about an older release — content under a version prefix such as v1-beta describes a prior API surface and may no longer be accurate.

@melissahenderson melissahenderson Jul 24, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a bit odd that all the text reads descriptively, except here, where there's an instruction. Was that intentional?

@brad-dow brad-dow Jul 24, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was intentional. While all of the other details were facts about the docs and Rafiki, this was meant to instruct an agent on what to do about encountering multiple versions. I can swap it out with something a bit less direct or rephrase it a bit if needed.

@melissahenderson melissahenderson Jul 24, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, I was just curious. It can stay as-is.

Comment thread packages/documentation/astro.config.mjs
- Wallet addresses are URL-based identifiers for financial accounts — not cryptocurrency wallets
- An Account Servicing Entity (ASE) is the regulated institution that holds and manages accounts on behalf of its users and runs Rafiki
- Peering is the trust relationship two Rafiki instances (run by different ASEs) establish to exchange payments directly — distinct from a payment between two end users
- Grants and GNAP (Grant Negotiation and Authorization Protocol) refer to Open Payments' authorization flow, distinct from OAuth`,

@melissahenderson melissahenderson Jul 24, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there supposed to be an ending back tick (`) in the last item?

@brad-dow brad-dow Jul 24, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The back tick closes the details object that started on line 383

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@melissahenderson melissahenderson melissahenderson approved these changes
@hajjimo hajjimo Awaiting requested review from hajjimo

Assignees

No one assigned

Labels

pkg: documentation Changes in the documentation package.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@brad-dow @melissahenderson